/**
 * 项目名：	Rumba Plan
 * 
 * 版权所有(C)，上海海鼎信息工程股份有限公司，2007，所有权利保留。
 * 
 * 文件名：	IQueryMgr.java
 * 模块说明：	
 * 修改历史：
 * May 14, 2007 - zhangyanbo - 创建。
 */
package com.hd123.rumba.qt;

import java.util.Hashtable;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.qt.def.IQueryDef;
import com.hd123.rumba.qt.def.ISessionValues;
import com.hd123.rumba.qt.result.QueryResultDescription;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;
import com.hd123.rumba.sql.ResultPage;
import com.hd123.rumba.user.IUser;

/**
 * 使用方法:<br>
 * <li>配置my.xml中的querySource和queryResult连接. 其中, querySource指向查询数据源,
 * 可以和business相同; queryResult为存放查询结果的数据库连接
 * <li>配置my.xml中的QTConstants参数. 可以使用默认值.
 * <li>运行后, 导入查询定义文件. 在doc/qt/queries中有两个定义例子.
 * 
 * @author zhangyanbo
 */
public interface IQueryMgr extends IManager {

  /**
   * 根据输入的参数返回一个查询结果描述. <br>
   * 如果存在最近一次的执行结果, 返回的qrd中的条件为那些值; <br>
   * 否则, qrd中的条件为查询定义的默认值. <br>
   * 构造界面内容可使用qrd.getCriteria()返回的内容.
   */
  public QueryResultDescription openQuery(IQueryDef queryDef, OperateContext operCtx)
      throws BusinessException, HibernateException;

  /**
   * 根据输入的参数查找相同的查询结果描述. 如果不存在, 返回null.
   * <p>
   * 相同的查询结果描述指的是
   * <li>查询文件名称(相对主目录)相同
   * <li>最后修改时间相同
   * <li>用户相同
   * <li>查询条件相同
   * 
   * @param queryDef
   *          查询定义
   * @param user
   *          查询用户
   * @param params
   *          条件, 包括查询条件和显示条件
   * @return 查询结果描述. 如果不存在, 返回null
   * @throws BusinessException
   * 
   * @see QueryResultDescription#getCriteria()
   */
  public QueryResultDescription findQueryResult(IQueryDef queryDef, IUser user, Hashtable params)
      throws BusinessException, HibernateException;

  /**
   * 创建一个查询线程并执行<br>
   * 后置条件:
   * <li>一个新的查询被调度执行
   * <li>一个新的查询结果描述被保存和返回, 执行线程的id被记录.
   * 
   * @param queryDef
   *          查询定义
   * @param user
   *          查询用户
   * @param params
   *          条件, 包括查询条件和显示条件
   * @return 查询结果描述
   * @throws BusinessException
   * @see QueryResultDescription#getCriteria()
   */
  public QueryResultDescription executeQuery(IQueryDef queryDef, ISessionValues sv, Hashtable params)
      throws BusinessException, HibernateException, MaxQueryException;

  public void executeQuery(QueryResultDescription qrd, ISessionValues sv) throws MaxQueryException,
      BusinessException, HibernateException;

  /**
   * 删除结果数据库中的一个表
   * 
   * @param tableName
   */
  public void deleteTable(String tableName) throws BusinessException, HibernateException;

  /**
   * 取消一个正在执行的查询.<br>
   * 后置条件:
   * <li>查询线程被终止
   * <li>查询结果描述qrd被删除
   * 
   * @param qrdUuid
   *          查询结果描述的uuid
   * @throws BusinessException
   */
  public void cancelQuery(String qrdUuid) throws BusinessException;

  /**
   * 取得查询结果, 并按照查询结果描述的显示条件排序和分页
   * 
   * @param base
   *          查询主目录
   * @param qrdUuid
   *          查询结果描述的uuid
   * @param page
   *          第几页
   * @return
   * @throws BusinessException
   */
  public ResultPage getResult(String base, String qrdUuid, int page) throws BusinessException,
      MaxQueryException;

  public ResultPage getResult(String base, String qrdUuid, int start, int limit)
      throws BusinessException, MaxQueryException;

  public ResultPage getResult(QueryResultDescription qrd, int page) throws BusinessException,
      MaxQueryException;

  public ResultPage getResult(QueryResultDescription qrd, int start, int limit)
      throws BusinessException, MaxQueryException;

  public ResultPage getSummary(String base, String qrdUuid) throws BusinessException,
      MaxQueryException;

  public ResultPage getSummary(QueryResultDescription qrd) throws BusinessException,
      MaxQueryException;

  public ThreadGroup getQtGroup();

  public void removeExpiredQueryResults() throws BusinessException;
}
